<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- ../src/examples/fridgemagnets.qdoc -->
<head>
  <title>Fridge Magnets Example</title>
    <style type="text/css">h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { color: black; }</style>
</head>
<body>
<h1 class="title">Fridge Magnets Example<br /><span class="subtitle"></span>
</h1>
<p>The Fridge Magnets example shows how to supply more than one type of MIME-encoded data with a drag and drop operation.</p>
<p align="center"><img src="classpath:com/trolltech/images/fridgemagnets-example.png" /></p><p>With this application the user can play around with a collection of fridge magnets, using drag and drop to form new sentences from the words on the magnets. The example consists of two classes:</p>
<ul>
<li><tt>DragLabel</tt> is a custom widget representing one single fridge magnet.</li>
<li><tt>FridgeMagnets</tt> provides the main application window.</li>
</ul>
<p>We will first take a look at the <tt>FridgeMagnets</tt> class, then we will take a quick look at the <tt>DragLabel</tt> class.</p>
<a name="fridgemagnets-class-implementation"></a>
<h2>FridgeMagnets Class Implementation</h2>
<p>The <tt>FridgeMagnets</tt> class extends QWidget:</p>
<pre>    public class FridgeMagnets extends QWidget {
        public FridgeMagnets(QWidget parent) {
            super(parent);
            QFile dictionaryFile;
            dictionaryFile = new QFile(&quot;classpath:com/trolltech/examples/words.txt&quot;);
            dictionaryFile.open(QIODevice.OpenModeFlag.ReadOnly);
            QTextStream inputStream = new QTextStream(dictionaryFile);</pre>
<p>In the constructor, we first open the file containing the words on our fridge magnets. QFile is an I/O device for reading and writing text and binary files and resources, and may be used by itself or in combination with QTextStream or QDataStream. We have chosen to read the contents of the file using the QTextStream class that provides a convenient interface for reading and writing text.</p>
<pre>            int x = 5;
            int y = 5;

            while (!inputStream.atEnd()) {
                String word = &quot;&quot;;
                word = inputStream.readLine();
                if (!word.equals(&quot;&quot;)) {
                    DragLabel wordLabel = new DragLabel(word, this);
                    wordLabel.move(x, y);
                    wordLabel.show();
                    x += wordLabel.sizeHint().width() + 2;
                    if (x &gt;= 245) {
                        x = 5;
                        y += wordLabel.sizeHint().height() + 2;
                    }
                }
            }</pre>
<p>Then we create the fridge magnets: As long as there is data (the QTextStream.atEnd() method returns true if there is no more data to be read from the stream), we read one line at a time using QTextStream's readLine() method. For each line, we create a <tt>DragLabel</tt> object using the read line as text, we calculate its position and ensure that it is visible by calling the QWidget.show() method.</p>
<pre>            QPalette newPalette = palette();
            newPalette.setColor(QPalette.ColorRole.Window, QColor.white);
            setPalette(newPalette);

            setMinimumSize(400, Math.max(200, y));
            setWindowIcon(new QIcon(&quot;classpath:com/trolltech/classpath:com/trolltech/images/qt-logo.png&quot;));
            setWindowTitle(tr(&quot;Fridge Magnets&quot;));</pre>
<p>We also set the <tt>FridgeMagnets</tt> widget's palette, minimum size, window icon and window title.</p>
<pre>            setAcceptDrops(true);
        }</pre>
<p>Finally, to enable our user to move the fridge magnets around, we must also set the <tt>FridgeMagnets</tt> widget's acceptDrops property. Setting this property to true announces to the system that this widget <i>may</i> be able to accept drop events (events that are sent when drag and drop actions are completed).</p>
<p>Note that to fully enable drag and drop in our <tt>FridgeMagnets</tt> widget, we must also reimplement the dragEnterEvent(), dragMoveEvent() and dropEvent() event handlers inherited from QWidget:</p>
<pre>        public void dragEnterEvent(QDragEnterEvent event) {</pre>
<p>When a a drag and drop action enters our widget, we will receive a drag enter <i>event</i>. QDragEnterEvent inherits most of its functionality from QDragMoveEvent, which in turn inherits most of its functionality from QDropEvent. Note that we must accept this event in order to receive the drag move events that are sent while the drag and drop action is in progress. The drag enter event is always immediately followed by a drag move event.</p>
<p>In our <tt>dragEnterEvent()</tt> implementation, we first determine whether we support the event's MIME type or not:</p>
<pre>            if (event.mimeData().hasFormat(&quot;application/x-fridgemagnet&quot;)) {
                if (children().contains(event.source())) {
                    event.setDropAction(Qt.DropAction.MoveAction);
                    event.accept();
                } else {
                    event.acceptProposedAction();
                }</pre>
<p>If the type is <tt>&quot;application/x-fridgemagnet&quot;</tt> and the event origins from any of this application's fridge magnet widgets, we first set the event's drop action using the QDropEvent.setDropAction() method. An event's drop action is the action to be performed on the data by the target. Qt.DropAction.MoveAction indicates that the data is moved from the source to the target.</p>
<p>Then we call the event's accept() method to indicate that we have handled the event. In general, unaccepted events might be propagated to the parent widget. If the event origins from any other widget, we simply accept the proposed action.</p>
<pre>            } else if (event.mimeData().hasText()) {
                event.acceptProposedAction();
            } else {
                event.ignore();
            }
        }</pre>
<p>We also accept the proposed action if the event's MIME type is <tt>text/plain</tt>, i.e&#x2e;, if QMimeData.hasText() returns true. If the event has any other type, on the other hand, we call the event's ignore() method allowing the event to be propagated further.</p>
<pre>        public void dragMoveEvent(QDragMoveEvent event) {
            if (event.mimeData().hasFormat(&quot;application/x-fridgemagnet&quot;)) {
                if (children().contains(event.source())) {
                    event.setDropAction(Qt.DropAction.MoveAction);
                    event.accept();
                } else {
                    event.acceptProposedAction();
                }
            } else if (event.mimeData().hasText()) {
                event.acceptProposedAction();
            } else {
                event.ignore();
            }
        }</pre>
<p>Drag move events occur when the cursor enters a widget, when it moves within the widget, and when a modifier key is pressed on the keyboard while the widget has focus. Our widget will receive drag move events repeatedly while a drag is within its boundaries. We reimplement the dragMoveEvent() method, and examine the event in the exact same way as we did with drag enter events.</p>
<a name="drop"></a><pre>        public void dropEvent(QDropEvent event) {
            if (event.mimeData().hasFormat(&quot;application/x-fridgemagnet&quot;)) {
                com.trolltech.qt.core.QMimeData mime = event.mimeData();</pre>
<p>Note that the dropEvent() event handler behaves slightly different: If the event origins from any of this application's fridge magnet widgets, we first get hold of the event's MIME data. The QMimeData class provides a container for data that records information about its MIME type. QMimeData objects associate the data that they hold with the corresponding MIME types to ensure that information can be safely transferred between applications, and copied around within the same application.</p>
<pre>                QByteArray itemData = mime.data(&quot;application/x-fridgemagnet&quot;);
                QDataStream dataStream = new QDataStream(itemData,
                       new QIODevice.OpenMode(QIODevice.OpenModeFlag.ReadOnly));

                String text = dataStream.readString();
                QPoint offset = new QPoint();
                offset.readFrom(dataStream);

                DragLabel newLabel = new DragLabel(text, this);
                newLabel.move(new QPoint(event.pos().x() - offset.x(),
                                         event.pos().y() - offset.y()));
                newLabel.show();

                if (children().contains(event.source())) {
                    event.setDropAction(Qt.DropAction.MoveAction);
                    event.accept();
                } else {
                    event.acceptProposedAction();
                }</pre>
<p>Then we retrieve the data associated with the <tt>&quot;application/x-fridgemagnet&quot;</tt> MIME type and use it to create a new <tt>DragLabel</tt> object. We use QDataStream and our own custom <tt>readString()</tt> and <tt>readQPoint()</tt> convenience methods (which we will describe shortly) to retrieve the moving fridge magnet's text and stored offset.</p>
<p>The QDataStream class provides serialization of binary data to a QIODevice (a data stream is a binary stream of encoded information which is 100% independent of the host computer's operating system, CPU or byte order).</p>
<p>Finally, we move the magnet to the event's position before we check if the event origins from any of this application's fridge magnet widgets. If it does, we set the event's drop action to Qt.DropAction.MoveAction and call the event's accept() method. Otherwise, we simply accept the proposed action like we did in the other event handlers.</p>
<pre>            } else if (event.mimeData().hasText()) {
                String[] pieces = event.mimeData().text().split(&quot;\\s+&quot;);
                QPoint position = event.pos();

                for (String piece : pieces) {
                    if (piece.equals(&quot;&quot;))
                        continue;

                    DragLabel newLabel = new DragLabel(piece, this);
                    newLabel.move(position);
                    newLabel.show();

                    position.add(new QPoint(newLabel.width(), 0));
                }

                event.acceptProposedAction();
            } else {
                event.ignore();
            }
        }</pre>
<p>If the event's MIME type is <tt>text/plain</tt>, i.e&#x2e;, if QMimeData.hasText() returns true, we retrieve its text and split it into words. For each word we create a new <tt>DragLabel</tt> action and show it at the event's position plus an offset depending on the number of words in the text. In the end we accept the proposed action.</p>
<p>If the event has any other type, we call the event's ignore() method allowing the event to be propagated further.</p>
<pre>        public static void main(String args[]) {
            QApplication.initialize(args);
            FridgeMagnets fridgeMagnets = new FridgeMagnets(null);
            fridgeMagnets.show();
            QApplication.exec();
        }
    }</pre>
<p>Finally, we provide a <tt>main()</tt> method to create and show our main widget when the example is run.</p>
<a name="draglabel-class-implementation"></a>
<h2>DragLabel Class Implementation</h2>
<p>Each fridge magnet is represented by an instance of the <tt>DragLabel</tt> class:</p>
<pre>        class DragLabel extends QLabel {
            private String labelText;

            public DragLabel(final String text, QWidget parent) {
                super(parent);

                QFontMetrics metrics = new QFontMetrics(font());
                QSize size = metrics.size(12, text);
                QImage image = new QImage(size.width() + 12, size.height() + 12,
                        QImage.Format.Format_ARGB32_Premultiplied);
                image.fill(0);

                QFont font = new QFont();
                font.setStyleStrategy(QFont.StyleStrategy.ForceOutline);</pre>
<p>In the <tt>DragLabel</tt> constructor, we first create a QImage object on which we will draw the fridge magnet's text and frame. Its size depends on the current font size, and its format is QImage.Format.Format_ARGB32_Premultiplied (i.e&#x2e;, the image is stored using a premultiplied 32-bit ARGB format (0xAARRGGBB)).</p>
<p>Then we constructs a font object that uses the application's default font, and set its style strategy. The style strategy tells the font matching algorithm what type of fonts should be used to find an appropriate default family. The QFont.StyleStrategy.ForceOutline forces the use of outline fonts.</p>
<pre>                QPainter painter = new QPainter();
                painter.begin(image);
                painter.setRenderHint(QPainter.RenderHint.Antialiasing);
                painter.setBrush(QColor.white);
                QRectF frame = new QRectF(0.5, 0.5, image.width() - 1,
                                          image.height() - 1);
                painter.drawRoundRect(frame, 10 * 100 / image.width(), 10 * 100 / image.height());

                painter.setFont(font);
                painter.setBrush(QColor.black);

                QRect rectangle = new QRect(new QPoint(6, 6), size);
                painter.drawText(rectangle, Qt.AlignmentFlag.AlignCenter.value(),
                                 text);
                painter.end();</pre>
<p>To draw the text and frame onto the image, we use the QPainter class. QPainter provides highly optimized methods to do most of the drawing GUI programs require. It can draw everything from simple lines to complex shapes like pies and chords. It can also draw aligned text and pixmaps.</p>
<p>A painter can be activated by passing a paint device to the constructor, or by using the begin() method as we do in this example. The end() method deactivates it. The end() method deactivates it. Note that the latter method is called automatically upon destruction when the painter is actived by its constructor. The QPainter.RenderHint.Antialiasing render hint ensures that the paint engine will antialias the edges of primitives if possible.</p>
<pre>                setPixmap(QPixmap.fromImage(image));
                labelText = text;
            }</pre>
<p>When the painting is done, we convert our image to a pixmap using QPixmap's fromImage() method. This method also takes an optional flags argument, and converts the given image to a pixmap using the specified flags to control the conversion (the flags argument is a bitwise-OR of the  Qt.ImageConversionFlags; passing 0 for flags sets all the default options).</p>
<p>Finally, we set the label's pixmap property and store the label's text for later use. Note that setting the pixmap clears any previous content, and disables the label widget's buddy shortcut, if any.</p>
<p>Earlier we set our main application widget's acceptDrops property and reimplemented QWidget's dragEnterEvent(), dragMoveEvent() and dropEvent() event handlers to support drag and drop. In addition, we must reimplement mousePressEvent() for our fridge magnet widget to make the user able to pick it up in the first place:</p>
<pre>            public void mousePressEvent(QMouseEvent event) {
                QByteArray itemData = new QByteArray();
                QDataStream dataStream;
                dataStream = new QDataStream(itemData,
                        new QIODevice.OpenMode(QIODevice.OpenModeFlag.WriteOnly));

                dataStream.writeString(labelText);
                QPoint position = new QPoint(event.pos().x() - rect().topLeft().x(),
                                             event.pos().y() - rect().topLeft().y());
                position.writeTo(dataStream);</pre>
<p>Mouse events occur when a mouse button is pressed or released inside a widget, or when the mouse cursor is moved. By reimplementing the mousePressEvent() method we ensure that we will receive mouse press events for the fridge magnet widget.</p>
<p>Whenever we receive such an event, we will first create a byte array to store our item data, and a QDataStream object to stream the data to the byte array.</p>
<pre>                com.trolltech.qt.core.QMimeData mimeData = new com.trolltech.qt.core.QMimeData();
                mimeData.setData(&quot;application/x-fridgemagnet&quot;, itemData);
                mimeData.setText(labelText);</pre>
<p>Then we create a new QMimeData object. As mentioned above, QMimeData objects associate the data that they hold with the corresponding MIME types to ensure that information can be safely transferred between applications. The setData() method sets the data associated with a given MIME type. In our case, we associate our item data with the custom <tt>&quot;application/x-fridgemagnet&quot;</tt> type.</p>
<p>Note that we also associate the magnet's text with the <tt>text/plain</tt> MIME type using QMimeData's setText() method. We have already seen how our main widget detects both these MIME types with its event handlers.</p>
<pre>                QDrag drag = new QDrag(this);
                drag.setMimeData(mimeData);

                drag.setHotSpot(new QPoint(event.pos().x() - rect().topLeft().x(),
                                           event.pos().y() - rect().topLeft().y()));
                drag.setPixmap(pixmap());

                hide();</pre>
<p>Finally, we create a QDrag object. It is the QDrag class that handles most of the details of a drag and drop operation, providing support for MIME-based drag and drop data transfer. The data to be transferred by the drag and drop operation is contained in a QMimeData object. When we call QDrag's setMimeData() method the ownership of our item data is transferred to the QDrag object.</p>
<p>We also specify the cursor's hot spot, i.e&#x2e;, its position while the drag is in progress, to be the top-left corner of our fridge magnet. We call the QDrag.setPixmap() method to set the pixmap used to represent the data during the drag and drop operation. Typically, this pixmap shows an icon that represents the MIME type of the data being transferred, but any pixmap can be used. In this example, we have chosen to use the fridge magnet image itself to make the magnet appear as moving, immediately hiding the activated widget.</p>
<pre>                if (drag.exec(Qt.DropAction.MoveAction) == Qt.DropAction.MoveAction)
                    close();
                else
                    show();
            }</pre>
<p>Then we start the drag using QDrag's start() method requesting that the magnet is moved when the drag is completed. The method returns the performed drop action; if this action is equal to Qt.DropAction.MoveAction we will close the acttvated fridge magnet widget because we then create a new one (with the same data) at the drop position (see the implementation of our main widgets <a href="#drop">dropEvent()</a> method). Otherwise, e.g&#x2e;, if the drop is outside our main widget, we simply show the widget in its original position.</p>
</body>
</html>
